"""
音频服务接口，用于管理音频播放
"""
from abc import ABC, abstractmethod
from typing import Dict, Any, List, Optional
from app.services.base_service import BaseService
from app.models.audio_item import AudioItem


class IAudioService(BaseService, ABC):
    """
    音频服务接口，用于管理音频播放
    """
    
    @abstractmethod
    def play(self, audio_path: str, volume: Optional[float] = None) -> bool:
        """
        播放音频文件
        
        @param audio_path: 音频文件路径
        @param volume: 音量，范围 0.0-1.0，如果为 None 则使用当前音量
        @return: 是否成功播放
        """
        pass
    
    @abstractmethod
    def play_item(self, audio_item: AudioItem) -> bool:
        """
        播放音频项
        
        @param audio_item: 音频项
        @return: 是否成功播放
        """
        pass
    
    @abstractmethod
    def stop_playback(self) -> bool:
        """
        停止当前播放
        
        @return: 是否成功停止
        """
        pass
    
    @abstractmethod
    def pause_playback(self, after_current: bool = True) -> bool:
        """
        暂停当前播放
        
        @param after_current: 是否在当前音频播放完成后暂停，True表示播放完当前音频后暂停，False表示立即暂停
        @return: 是否成功暂停
        """
        pass
    
    @abstractmethod
    def resume_playback(self) -> bool:
        """
        恢复播放
        
        @return: 是否成功恢复
        """
        pass
    
    @abstractmethod
    def start_playback(self) -> bool:
        """
        手动开始播放
        
        @return: 是否成功开始播放
        """
        pass
    
    @abstractmethod
    def is_playing(self) -> bool:
        """
        检查是否正在播放
        
        @return: 是否正在播放
        """
        pass
    
    @abstractmethod
    def add_to_queue(self, audio_item: AudioItem) -> None:
        """
        将音频添加到播放队列底部
        
        @param audio_item: 音频项
        """
        pass
    
    @abstractmethod
    def add_to_queue_front(self, audio_item: AudioItem) -> None:
        """
        将音频添加到播放队列顶部（临时插入）
        
        @param audio_item: 音频项
        """
        pass
    
    @abstractmethod
    def remove_from_queue(self, item_id: str) -> bool:
        """
        从播放队列中移除音频
        
        @param item_id: 音频项 ID
        @return: 是否成功移除
        """
        pass
    
    @abstractmethod
    def clear_queue(self) -> None:
        """
        清空播放队列
        """
        pass
    
    @abstractmethod
    def get_queue(self) -> List[AudioItem]:
        """
        获取播放队列
        
        @return: 播放队列
        """
        pass
    
    @abstractmethod
    def get_current_item(self) -> Optional[AudioItem]:
        """
        获取当前播放的音频项
        
        @return: 当前播放的音频项，如果没有则返回 None
        """
        pass
    
    @abstractmethod
    def set_volume(self, volume: float) -> None:
        """
        设置音量
        
        @param volume: 音量值，范围 0.0-1.0
        """
        pass
    
    @abstractmethod
    def get_volume(self) -> float:
        """
        获取当前音量
        
        @return: 当前音量值
        """
        pass
    
    @abstractmethod
    def configure(self, config: Dict[str, Any]) -> None:
        """
        配置音频服务
        
        @param config: 配置字典
        """
        pass
    
    @abstractmethod
    def start(self) -> bool:
        """
        启动服务
        
        @return: 是否成功启动
        """
        pass
    
    @abstractmethod
    def stop(self) -> bool:
        """
        停止服务
        
        @return: 是否成功停止
        """
        pass 